ODArbitrator

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODArbitrator

Superclasses
ODObject
Subclasses
none

An object of the ODArbitrator class manages temporary ownership of shared resources or features among parts.

Description
A focus is a designation of ownership of a given shared resource. Foci are defined according to the type of resource that each represents. For example, focus types include the keystroke focus, menu bar focus, and selection focus. Other foci can be associated with system-wide resources like serial ports. Foci are owned by frames. The frame's part relinquishes ownership of foci when asked to, such as when another part is requesting ownership or when a frame is deleted.
When a document is opened, the session object creates a single arbitrator object. All parts of that document share the arbitrator object; you can obtain a reference to it by calling the session object's GetArbitrator method (page 605).
The OpenDoc arbitrator keeps track of which part owns a focus by consulting the focus module for that focus. A focus is registered if it has a focus module. The arbitrator is used by the OpenDoc dispatcher to determine where to send events. For example, the dispatcher, which is responsible for distributing events to part editors, directs keyboard events to the part that currently owns the keystroke focus and menu events to the part that currently owns the menu bar focus.
Foci may be exclusive or nonexclusive. All of the standard foci defined by OpenDoc are exclusive, meaning that only one frame at a time can own a focus. The ODArbitrator class also supports nonexclusive foci, which can be owned by several frames. In such cases, the arbitrator provides a central location in which you can record and later obtain a list of the owners for that focus.
For more information related to foci, focus sets, focus types, and focus modules, see the descriptions for the classes ODFocusModule (page 264), ODFocusOwnerIterator (page 278), ODFocusSet (page 285), and ODFocusSetIterator (page 290). For more information related to the dispatcher, see the ODDispatcher class description (page 110).

Methods
This section presents summary descriptions of the ODArbitrator methods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Creating a Focus Set

CreateFocusSet
Creates and initializes a focus set.
Focus Transfer

RequestFocus
Requests that the ownership of the specified focus be assigned to the specified frame.
RequestFocusSet
Requests that the ownership of each focus in the specified focus set be assigned to the specified frame.
RelinquishFocus
Called by the current owner of the specified focus to relinquish ownership of it.
RelinquishFocusSet
Called by the current owner of each focus in the specified focus set to relinquish ownership of it.
TransferFocus
Directly transfers a focus from its current owner to another.
TransferFocusSet
Assigns the specified frame as the owner of each focus in the specified focus set.
Registering Focus Modules

IsFocusRegistered
Returns a Boolean value that indicates whether the specified focus is registered.
RegisterFocus
Adds the specified focus module for the specified focus.
UnregisterFocus
Removes the association between the specified focus and the focus module that manages it.
GetFocusModule
Returns a reference to a focus module for the specified focus.
Determining Focus Ownership

IsFocusExclusive
Returns a Boolean value that indicates whether the specified focus is exclusive.
AcquireFocusOwner
Returns a reference to the frame that owns the specified exclusive focus.
CreateOwnerIterator
Creates a focus-owner iterator to give callers access to the frames that own a nonexclusive focus.

Methods
AcquireFocusOwner
CreateFocusSet
CreateOwnerIterator
GetFocusModule
IsFocusExlusive
IsFocusRegistered
RegisterFocus
RelinquishFocus
RelinquishFocusSet
RequestFocus
RequestFocusSet
TransferFocus
TransferFocusSet
UnregisterFocus